home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / heap3.com / HEAP3.DOC < prev    next >
Encoding:
Text File  |  1988-11-28  |  4.7 KB  |  122 lines
  1.  
  2.                         Turbo Pascal 5.0
  3.                        Heap3 Documentation
  4.  
  5.  
  6. INTRODUCTION
  7.  
  8. In response to a user's request, here's a Turbo Pascal 5.0 (TP5)
  9. unit that implements a heap manager similar to Turbo Pascal 3.0
  10. (TP3). The main differences between this heap manager (Heap3) and
  11. the one built into TP5's System unit are:
  12.  
  13.   1.  Heap3 always allocates an even multiple of 8 bytes (TP5
  14.       allocates exactly the number requested).
  15.   2.  Heap3 stores its free list in address order as a linked
  16.       list that runs throughout the heap (TP5 stores its free
  17.       list at the top of the heap and grows downwards.)
  18.   3.  Heap3 supplies only GetMem, FreeMem, MemAvail and MaxAvail
  19.       (TP5 also supports New, Dispose, Mark and Release).
  20.  
  21. For more information about these differences, refer to the notes
  22. at the end of this documentation.
  23.  
  24.  
  25.  
  26. HEAP3 INTERFACE DECLARATIONS
  27.  
  28. Here's the TP5 interface for unit Heap3:
  29.  
  30.   unit Heap3;
  31.  
  32.   interface
  33.  
  34.   procedure GetMem(var P; Size: Word);
  35.   procedure FreeMem(var P; Size: Word);
  36.  
  37.   function MemAvail: LongInt;
  38.   function MaxAvail: LongInt;
  39.  
  40.  
  41.  
  42. TECHNICAL NOTES:
  43.  
  44. 1.  You should make Heap3 the first unit used in a USES clause.
  45.     In addition, rebuild all units that use System's heap
  46.     routines. For example, if you are going to use Heap3 in a
  47.     program named TEST.PAS, you should completely rebuild all of
  48.     the units used by TEST. And be sure to place a USES HEAP3 in
  49.     every unit that calls any TP5 heap management routines
  50.     (GetMem, FreeMem, New, Dispose, Mark, Release, MaxAvail,
  51.     MemAvail). In this way, all references to heap routines in
  52.     these other units will now link in Heap3's routines (instead
  53.     of System's).
  54.  
  55.     Of course, this requirement could present an insurmountable
  56.     problem if you don't have the source to SOMEUNIT.TPU and it
  57.     uses the heap. In such a case, you can't use Heap3 in the
  58.     same program as SOMEUNIT unless SOMEUNIT has some provision
  59.     for intercepting heap allocation and deallocation requests.
  60.     TP5's Graph unit is such an example; though it uses the heap
  61.     to allocate and deallocate memory, it has two "hooks"
  62.     (GraphGetMemPtr and GraphFreeMemPtr) that allow a user
  63.     program to insert its own heap routines. Thus, you CAN use
  64.     Heap3 and Graph in the same program, but you should place
  65.     Heap3 first in the USES clause (so its initialization code is
  66.     executed first) and you MUST point GraphGetMemPtr and
  67.     GraphFreeMemPtr at your own routines (see TP5 Reference
  68.     Manual for details).
  69.  
  70. 2.  Do not make calls to New, Dispose, Mark or Release in any
  71.     program that uses the Heap3 unit. These routines are not
  72.     supported by Heap3. Since Heap3 uses the data structures that
  73.     are declared in the System unit, mixing calls to heap
  74.     routines from System and Heap3 will have unpredictable (and
  75.     probably catastrophic) consequences. To help prevent these
  76.     types of errors, Heap3 contains "dummy" procedure
  77.     declarations for New, Dispose, Mark and Release. When any of
  78.     these "dummy" routines is referenced in a program that uses
  79.     Heap3, error #85 (semi-colon expected) will be generated.
  80.  
  81. 3.  To use Heap3, all calls to
  82.  
  83.       New(x);
  84.       Dispose(x);
  85.  
  86.     will have to be changed to
  87.  
  88.       GetMem(x, SizeOf(x^));
  89.       FreeMem(x, SizeOf(x^));
  90.  
  91.     Of course, you can hardcode the SizeOf() argument and thus
  92.     the following procedure calls would be valid:
  93.  
  94.       GetMem(x, 12);
  95.       FreeMem(x, 36);
  96.  
  97.     The parameter to Heap3's GetMem and FreeMem is an untyped var
  98.     parameter. This means you don't have to typecast every
  99.     pointer you pass to GetMem and FreeMem, but it also means you
  100.     can pass a variable of any type (by accident).
  101.  
  102. 4.  With version 3.0 of Turbo Pascal, a runtime error ($FF
  103.     Heap/Stack collision) occurred when insufficient dynamic
  104.     memory was available to satisfy a call to New or GetMem.
  105.     TP5's heap manager supports a heap error handler called
  106.     HeapError (see the "Inside Turbo Pascal" chapter for more
  107.     information about HeapError).
  108.  
  109.     Similarly, instead of generating a runtime error like TP3,
  110.     Heap3's GetMem returns a nil pointer when the heap is full.
  111.     Therefore, after each call to GetMem(P, SomeBytes), your
  112.     program can (and should) verify that the allocation request
  113.     succeeded by checking P <> nil.
  114.  
  115.     Also, unlike the TP5 heap manager built into the System unit,
  116.     Heap3 does NOT give an error if P does not point into the
  117.     heap and a FreeMem(P, SomeBytes) is called.
  118.  
  119. 5.  The smallest heap allocation using Heap3 is 8 bytes, and
  120.     allocation requests will always be rounded to an even
  121.     multiple of 8 bytes.
  122.